BE-306: HashQL: PostgreSQL translation by indietyp · Pull Request #8526 · hashintel/hash

indietyp · 2026-03-08T15:55:00Z

🌟 What is the purpose of this PR?

Implements the postgres compilation backend for HashQL. Takes the MIR control flow graph (after execution analysis has assigned basic blocks to backends and partitioned them into islands) and compiles the Postgres-assigned islands into SQL SELECT statements.

🔍 What does this change?

Postgres compiler (eval/src/postgres/mod.rs):
Top-level entry point. Compiles a GraphRead body island-by-island into a PreparedQuery (a SelectStatement + deduplicated Parameters list). Each Postgres island becomes a CROSS JOIN LATERAL subquery returning a continuation composite value. The continuation carries filter (keep/reject/passthrough), block (next basic block), and locals/values (live-out data for the interpreter to resume from).

Filter compiler (eval/src/postgres/filter/):
Walks the MIR basic blocks within an island and compiles each statement into SQL expressions. Uses an explicit frame stack (not recursion) to handle SwitchInt terminators: each branch becomes a CASE WHEN arm, with the discriminant cast to ::int to avoid boolean/integer type mismatches in PostgreSQL. Out-of-island branches produce continuation values that encode which block to resume and what locals to carry.

Projections (eval/src/postgres/projections.rs):
Maps EntityPath variants to SQL column references or JSONB extraction expressions. Tracks which table joins are needed and only requests them when a path is actually referenced. Handles the split between "column-backed" paths (entity_uuid, web_id, etc.) and "JSONB-backed" paths (properties, type IDs).

Parameters (eval/src/postgres/parameters.rs):
Builds the $1, $2, ... parameter list for the prepared statement. Deduplicates by identity. Each Parameter variant represents a different source: Input (user-provided values), Symbol/Primitive/Int (query literals), Env (closure captures), TemporalAxis (execution context). The CompiledQuery return type exposes which indices correspond to which sources so the interpreter can bind them.

Continuation (eval/src/postgres/continuation.rs):
Builds the ROW(filter, block, locals, values)::continuation composite values that encode island exit state. Handles the three exit cases: passthrough (NULL continuation), filter-only (just a boolean), and full exit (block + live-out locals serialized as parallel int[]/jsonb[] arrays).

Traverse (eval/src/postgres/traverse.rs):
Compiles graph traversal requirements into SQL joins. Reads the island's provides set to determine which entity paths need table joins, then requests them from the database context layer.

Error infrastructure (eval/src/postgres/error.rs):
Diagnostic types for compilation errors (unsupported operations, type mismatches, missing paths) with span-accurate source locations.

Context (eval/src/context.rs):
DatabaseContext trait and implementation that the compiler uses to request table aliases, register joins, and access the schema. Bridges between the HashQL type system and the graph-store query builder.

Compiletest suite (compiletest/src/suite/eval_postgres.rs):
New compiletest suite that runs the full pipeline (parse, type-check, lower to MIR, run execution analysis, compile to SQL) and compares the output against blessed .stdout files. Also emits .aux.mir secondary outputs showing the MIR after execution analysis for debugging.

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

This PR:

does not modify any publishable blocks or libraries, or modifications do not need publishing

📜 Does this require a change to the docs?

The changes in this PR:

are internal and do not require a docs change

🕸️ Does this require a change to the Turbo Graph?

The changes in this PR:

do not affect the execution graph

⚠️ Known issues

OFFSET 0 on lateral subqueries is a workaround for PostgreSQL inlining composites; see continuation.rs doc comments for details.

🛡 What tests cover this?

Filter compiler unit tests (filter/tests.rs, ~1000 lines) using insta snapshots covering: straight-line blocks, branching CFGs, diamond merges, island exits, projections, property access, parameter deduplication, lateral subquery generation
30+ compiletest cases under eval/tests/ui/postgres/ covering end-to-end compilation: comparison operators, entity field access, input parameters, let bindings, if-expressions, nested branching, environment captures, list/dict/struct/tuple construction, multiple filters, mixed-source filters

❓ How to test this?

cargo nextest run -p hashql-eval
cargo run --package hashql-compiletest -- run

feat: checkpoint (II) feat: checkpoint (III) feat: snapshot vec feat: add dedicated filter feat: checkpoint feat: filter implementation feat: filter implementation (mostly) done chore: environment capture note chore: always postgres bigint feat: target clone feat: simplify lookup feat: move storage up feat: eval entity path chore: checkpoint chore: checkpoint chore: find entrypoint feat: eval context feat: eval cleanup chore: cleanup feat: track index feat: wire up filter feat: add error reporting chore: checkpoint feat: add traverse, and first postgres compiler outline feat: traverse bitmap feat: move traversal out feat: projections feat: projections fix: clippy feat: subquery projection for lateral feat: checkpoint feat: test plan feat: checkpoint feat: checkpoint – failing tests ;-; feat: checkpoint – failing tests ;-; feat: checkpoint — passing tests fix: import fix: entity type feat: checkpoint feat: attribute a cost to terminator placement switches fix: import feat: checkpoint feat: checkpoint chore: lint

cursor · 2026-03-08T15:55:05Z

PR Summary

High Risk
Adds a new MIR→SQL compilation pipeline and changes the Postgres query AST/types, which could affect correctness of generated SQL and runtime query execution paths.

Overview
Implements a new HashQL PostgreSQL backend that compiles GraphRead MIR (after execution/island analysis) into a prepared SELECT with deduplicated $N parameters, including continuation-based CROSS JOIN LATERAL subqueries for Postgres-placed filter islands.

Adds new evaluation infrastructure in hashql-eval (context, postgres modules) for live-out analysis, diagnostics, lazy join planning, entity-path→SQL mapping, and SQL lowering of filter CFGs into CASE expressions (including island exits that transfer block/local/value state).

Expands the Postgres query builder to support boolean types, updates workspace dependencies accordingly, and introduces extensive test coverage via a new compiletest suite (eval/postgres) plus snapshot-based unit tests and UI fixtures for end-to-end SQL output validation.

^{Reviewed by Cursor Bugbot for commit 80d2eaf. Bugbot is set up for automated code reviews on this repo. Configure here.}

vercel · 2026-03-08T15:55:05Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hash	Ready	Preview, Comment	May 11, 2026 11:11am
petrinaut	Ready	Preview	May 11, 2026 11:11am

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
hashdotdesign	Ignored	Preview	May 11, 2026 11:11am
hashdotdesign-tokens	Ignored	Preview	May 11, 2026 11:11am

indietyp · 2026-03-08T15:55:21Z

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

This stack of pull requests is managed by Graphite. Learn more about stacking.

augmentcode · 2026-03-08T15:58:15Z

🤖 Augment PR Summary

Summary: Adds a PostgreSQL compilation backend for HashQL by lowering MIR execution islands into SQL SELECT statements with continuation-based control flow.

Key changes:

Introduces eval/src/postgres/ with a top-level PostgresCompiler that compiles GraphRead filters island-by-island into lateral subqueries returning a typed continuation composite.
Adds a CFG-to-SQL filter compiler (postgres/filter) that builds CASE WHEN trees iteratively (explicit frame stack) and emits island-exit continuations carrying live-out locals.
Implements parameter deduplication (postgres/parameters.rs) and lazy join planning/projection mapping (postgres/projections.rs, postgres/traverse.rs).
Adds new eval-level EvalContext + live-out dataflow computation used by the Postgres backend.
Extends diagnostics to include Postgres backend categories (postgres/error.rs + eval/src/error.rs integration).
Adds a new compiletest suite (compiletest/src/suite/eval_postgres.rs) and a sizable set of end-to-end UI test fixtures under eval/tests/ui/postgres/, plus MIR snapshot tests for hard-to-produce MIR shapes.

Technical notes: Compiled filter islands are materialized with CROSS JOIN LATERAL and OFFSET 0 to prevent Postgres from inlining/duplicating CASE trees; selected entity paths are driven by the island provides set and only trigger joins when referenced.

_{🤖 Was this summary useful? React with 👍 or 👎}

augmentcode

Review completed. 2 suggestions posted.

Comment augment review to trigger a new review at any time.

codspeed-hq · 2026-03-08T15:59:34Z

Merging this PR will not alter performance

✅ 80 untouched benchmarks

_{Comparing bm/be-306-hashql-postgres-translation (80d2eaf) with bm/be-457-hashql-mir-execution-pipeline-extensions-for-postgres (44ba0c2)}

codecov · 2026-03-08T16:20:48Z

Codecov Report

❌ Patch coverage is 94.73985% with 92 lines in your changes missing coverage. Please review.
✅ Project coverage is 62.72%. Comparing base (44ba0c2) to head (80d2eaf).

Files with missing lines	Patch %	Lines
libs/@local/hashql/eval/src/postgres/filter/mod.rs	89.30%	43 Missing and 5 partials ⚠️
libs/@local/hashql/eval/src/postgres/error.rs	0.00%	22 Missing ⚠️
...bs/@local/hashql/eval/src/postgres/filter/tests.rs	98.72%	4 Missing and 2 partials ⚠️
libs/@local/hashql/eval/src/postgres/mod.rs	96.95%	4 Missing and 1 partial ⚠️
libs/@local/hashql/eval/src/postgres/traverse.rs	96.00%	5 Missing ⚠️
libs/@local/hashql/eval/src/context.rs	95.55%	1 Missing and 1 partial ⚠️
libs/@local/hashql/eval/src/postgres/parameters.rs	98.26%	2 Missing ⚠️
...src/store/postgres/query/expression/conditional.rs	0.00%	1 Missing ⚠️
libs/@local/hashql/eval/src/error.rs	0.00%	1 Missing ⚠️

Additional details and impacted files

@@                                         Coverage Diff                                         @@
##           bm/be-457-hashql-mir-execution-pipeline-extensions-for-postgres    #8526      +/-   ##
===================================================================================================
+ Coverage                                                            62.31%   62.72%   +0.40%     
===================================================================================================
  Files                                                                 1354     1363       +9     
  Lines                                                               137313   139062    +1749     
  Branches                                                              5793     5818      +25     
===================================================================================================
+ Hits                                                                 85567    87227    +1660     
- Misses                                                               50839    50919      +80     
- Partials                                                               907      916       +9

Flag	Coverage Δ
apps.hash-ai-worker-ts	`1.41% <ø> (ø)`
apps.hash-api	`0.00% <ø> (ø)`
blockprotocol.type-system	`40.84% <ø> (ø)`
local.claude-hooks	`0.00% <ø> (ø)`
local.harpc-client	`51.24% <ø> (ø)`
local.hash-backend-utils	`2.81% <ø> (ø)`
local.hash-graph-sdk	`9.63% <ø> (ø)`
local.hash-isomorphic-utils	`0.00% <ø> (ø)`
rust.antsi	`0.00% <ø> (ø)`
rust.error-stack	`90.87% <ø> (ø)`
rust.harpc-codec	`84.70% <ø> (ø)`
rust.harpc-net	`96.24% <ø> (+0.04%)`	⬆️
rust.harpc-tower	`67.03% <ø> (ø)`
rust.harpc-types	`0.00% <ø> (ø)`
rust.harpc-wire-protocol	`92.23% <ø> (ø)`
rust.hash-codec	`72.76% <ø> (ø)`
rust.hash-graph-api	`2.52% <ø> (ø)`
rust.hash-graph-authorization	`62.34% <ø> (ø)`
rust.hash-graph-postgres-store	`26.81% <0.00%> (-0.01%)`	⬇️
rust.hash-graph-store	`37.76% <ø> (ø)`
rust.hash-graph-temporal-versioning	`47.95% <ø> (ø)`
rust.hash-graph-types	`0.00% <ø> (ø)`
rust.hash-graph-validation	`83.45% <ø> (ø)`
rust.hashql-ast	`87.23% <ø> (ø)`
rust.hashql-compiletest	`29.63% <ø> (ø)`
rust.hashql-core	`82.44% <ø> (ø)`
rust.hashql-diagnostics	`72.43% <ø> (ø)`
rust.hashql-eval	`81.08% <94.79%> (+18.09%)`	⬆️
rust.hashql-hir	`89.06% <ø> (ø)`
rust.hashql-mir	`92.08% <ø> (ø)`
rust.hashql-syntax-jexpr	`94.06% <ø> (ø)`

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

cursor

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 8b510e5. Configure here.}

cursor · 2026-04-29T13:44:47Z

+                    ColumnName::from(Identifier::from("b")),
+                    ColumnName::from(Identifier::from("v")),
+                ],
+            });


UNNEST lateral flag contradicts required LATERAL semantics

Medium Severity

The FromItem::Function for the UNNEST call sets lateral: false, but the function body references columns from the preceding "eit" table alias (eit.base_urls, eit.versions). In PostgreSQL, explicit CROSS JOIN requires the LATERAL keyword for the right-hand side to reference columns from the left. The doc comment on line 185 correctly states CROSS JOIN LATERAL UNNEST(...), but the code passes lateral: false, which would produce invalid SQL when the entity type IDs path is accessed.

^{Reviewed by Cursor Bugbot for commit 8b510e5. Configure here.}

indietyp added 2 commits March 8, 2026 16:17

feat: move hunk up

966fea9

graphite-app Bot assigned indietyp Mar 8, 2026

github-actions Bot added area/deps Relates to third-party dependencies (area) area/infra Relates to version control, CI, CD or IaC (area) area/libs Relates to first-party libraries/crates/packages (area) type/eng > backend Owned by the @backend team area/tests New or updated tests labels Mar 8, 2026

fix: remove test plan

0fb8c27

indietyp mentioned this pull request Mar 8, 2026

BE-456: HashQL: Entity type model enrichment and graph store query extensions #8524

Open

3 tasks

github-actions Bot removed the area/infra Relates to version control, CI, CD or IaC (area) label Mar 8, 2026

augmentcode Bot reviewed Mar 8, 2026

View reviewed changes

Comment thread libs/@local/hashql/eval/src/postgres/mod.rs

Comment thread libs/@local/hashql/eval/src/postgres/traverse.rs Outdated

vercel Bot deployed to Preview – petrinaut March 8, 2026 15:58 View deployment

github-advanced-security AI found potential problems Mar 8, 2026

View reviewed changes

vercel Bot deployed to Preview – hash March 8, 2026 16:14 View deployment

indietyp force-pushed the bm/be-306-hashql-postgres-translation branch from 33a9dcc to 8c07a05 Compare March 8, 2026 16:15

indietyp force-pushed the bm/be-457-hashql-mir-execution-pipeline-extensions-for-postgres branch from 5d95ba7 to 1aa0f1c Compare March 8, 2026 16:15

vercel Bot deployed to Preview – petrinaut March 8, 2026 16:18 View deployment

cursor Bot reviewed Mar 8, 2026

View reviewed changes

Comment thread libs/@local/hashql/eval/src/postgres/filter/mod.rs

Comment thread libs/@local/hashql/eval/src/postgres/filter/tests.rs Outdated

vercel Bot deployed to Preview – hash April 29, 2026 13:21 View deployment

This comment was marked as duplicate.

Sign in to view

feat: add body to snapshots

80d2eaf

indietyp force-pushed the bm/be-306-hashql-postgres-translation branch from 02e5f27 to 8b510e5 Compare April 29, 2026 13:37

indietyp force-pushed the bm/be-457-hashql-mir-execution-pipeline-extensions-for-postgres branch from a675701 to 3050d4a Compare April 29, 2026 13:37

vercel Bot deployed to Preview – petrinaut April 29, 2026 13:41 View deployment

cursor Bot reviewed Apr 29, 2026

View reviewed changes

vercel Bot deployed to Preview – hash April 29, 2026 13:48 View deployment

This was referenced Apr 29, 2026

BE-522: HashQL: Expand stdlib type system with temporal types #8674

Open

BE-523: HashQL: Suspendable interpreter with structured values and input system #8675

Open

indietyp force-pushed the bm/be-306-hashql-postgres-translation branch from 8b510e5 to c484cc9 Compare April 29, 2026 15:51

indietyp force-pushed the bm/be-457-hashql-mir-execution-pipeline-extensions-for-postgres branch from 3050d4a to 5552cbb Compare April 29, 2026 15:51

vercel Bot deployed to Preview – petrinaut April 29, 2026 15:54 View deployment

vercel Bot deployed to Preview – hash April 29, 2026 16:01 View deployment

This was referenced May 4, 2026

BE-525: HashQL: Remove implicit type-widening from Integer operations, and make comparison size aware #8693

Open

BE-524: HashQL: Remove island schedule module #8694

Open

indietyp force-pushed the bm/be-306-hashql-postgres-translation branch from c484cc9 to b399240 Compare May 4, 2026 11:34

indietyp force-pushed the bm/be-457-hashql-mir-execution-pipeline-extensions-for-postgres branch from 5552cbb to 60da845 Compare May 4, 2026 11:34

vercel Bot deployed to Preview – petrinaut May 4, 2026 11:38 View deployment

vercel Bot deployed to Preview – hash May 4, 2026 11:47 View deployment

This was referenced May 4, 2026

BE-512: HashQL: Allow cross-backend transitions for SwitchInt terminators #8696

Open

BE-513: HashQL: Rework dynamic aggregate size estimation #8697

Open

indietyp force-pushed the bm/be-457-hashql-mir-execution-pipeline-extensions-for-postgres branch from 60da845 to fd9a3a8 Compare May 8, 2026 08:33

indietyp force-pushed the bm/be-306-hashql-postgres-translation branch from b399240 to 966d6c1 Compare May 8, 2026 08:33

vercel Bot deployed to Preview – petrinaut May 8, 2026 08:37 View deployment

vercel Bot deployed to Preview – hash May 8, 2026 08:45 View deployment

indietyp force-pushed the bm/be-457-hashql-mir-execution-pipeline-extensions-for-postgres branch from fd9a3a8 to 44ba0c2 Compare May 11, 2026 10:58

indietyp force-pushed the bm/be-306-hashql-postgres-translation branch from 966d6c1 to 80d2eaf Compare May 11, 2026 10:58

vercel Bot deployed to Preview – petrinaut May 11, 2026 11:02 View deployment

vercel Bot deployed to Preview – hash May 11, 2026 11:11 View deployment

Conversation

indietyp commented Mar 8, 2026

🌟 What is the purpose of this PR?

🔍 What does this change?

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

📜 Does this require a change to the docs?

🕸️ Does this require a change to the Turbo Graph?

⚠️ Known issues

🛡 What tests cover this?

❓ How to test this?

Uh oh!

cursor Bot commented Mar 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Summary

Uh oh!

vercel Bot commented Mar 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

indietyp commented Mar 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

augmentcode Bot commented Mar 8, 2026

Uh oh!

augmentcode Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

codspeed-hq Bot commented Mar 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging this PR will not alter performance

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codecov Bot commented Mar 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Uh oh!

This comment was marked as duplicate.

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cursor Bot Apr 29, 2026

Choose a reason for hiding this comment

UNNEST lateral flag contradicts required LATERAL semantics

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

3 participants

cursor Bot commented Mar 8, 2026 •

edited

Loading

vercel Bot commented Mar 8, 2026 •

edited

Loading

indietyp commented Mar 8, 2026 •

edited

Loading

codspeed-hq Bot commented Mar 8, 2026 •

edited

Loading

codecov Bot commented Mar 8, 2026 •

edited

Loading